NOTE: This documentation is not even close to being complete.
ShadowBot is shareware, $20. To register, send cash, check, or money order to:
ShadowBot Registration
c/o John Bafford
6 Cedar Springs Ct.
Baltimore, MD 21228
If you read this file, you shouldn’t have any problems setting up ShadowBot. PLEASE read this file first because I would much rather spend time coding ShadowBot than answering questions whose answers can be found in this file (or others distributed with ShadowBot).
Also, everything has balloon help, which is often better than what's in this documentation.
Connection Settings
This is one of the most important of the configuration windows. Without this window properly set up, ShadowBot cannot connect to an IRC server.
Nick - This is the bot’s nickname. It must be nine characters or shorter.
Username - This is the bot’s username.
Command character - This is the bot’s command character. All commands, with few exceptions, must be preceded by this character so the bot knows you’re talking to it. By unchecking the ‘Required’ checkbox, you can make the command character optional. Commands typed into the console require the command character.
DCC Command Character - This is the command character used in DCC chat.
Connect Script - If the Use Connect Script button is checked, the bot executes these (IRC) commands on connection before joining channels.
Auto-Connect - If this is checked, the bot will automatically log on when it loads up. Press and hold the shift key down while the splash screen is open to temporarally disable this.
Reconnect to server - Allows the bot to attempt to recnnect to the server on its own when it's disconnected.
Display MOTD - If unchecked, this supresses the display of the MOTD.
Use Identd - Allows the bot to use Identd to remove the ~ from the username.
MODE +d - Makes the bot deaf to channel messages. (The command !deaf has the same effect; the command !hear sets the mode to -d.)
MODE +i - Makes the bot invisible. (Unless you're on a channel it's on, you can't see that it's on that channel.)
Server List
This is another extremely important configuration window.
Without setting up a server, ShadowBot cannot connect to IRC. The Server List is an easy way to set up a list of servers that the bot can attempt to connect to.
In the largest portion of the window is taken up by the server list itself. A new bot will contain only one entry in the serverlist: "irc.server.com 6667 []" (this server doesn't work).
Each line in the server list is broken up into three parts: the server, the port, and the (optional) connection password. Thes three items are edited from the entry boxes at the bottom of the window.
The Add, Copy, and Delete buttons are used to Add entries to the serverlist, duplicate an entry, and delete entries from the list.
Owner Settings
The second most important of the configuration windows, Owner Settings allows you to configure the bot to recognize you as it’s owner.
Nick - Put your usual nickname here.
Hostmask - Put your hostmask here. If you’re not sure about your hostmask, see the section on hostmasks near the end of this file.
Email address (optional) - Allows you to set an email address that will be visible when someone asks the bot for your email address.
Infoline (optional) - A line the bot will send out when it sees you join a channel.
Real Name (optional) - People will see this line, if you have set it, when they do a WHOIS on you from the bot.
Password (optional) - Password used to identify yourself to the bot. Passwords are case sensitive.
Password is Required - If on, you MUST use the !ident [nick] password command to gain access. Otherwise, you only need to identify yourself when you're not using your normal hostmask.
Channel Settings
This window allows you to set what channels the bot is to join by default. The channel list on the right side of the window lets you set up to ten channels (IRC limitation). By selecting a channel from the list, its settings appear in the left side of the window.
The Default channel - The default channel contains settings that will be used if you ask the bot to join channels not in its channel list. You cannot change its name. It is the first channel in the list, named "--Default--".
AutoJoin - If this is set, the bot automatically joins the channel.
Channel Modes - Channel modes can be set to either On, Off, or Ignore. When set to Ignore, the bot does not care what that particular mode is set to. If the mode is set to On, the bot will set that mode on if someone under a required access turns it off. The same is true if modes are set to Off: if someone turns it on, it is set back off.
Only Listed Users - If a user not in the user list enters, they are automaically kicked.
Strict Opping - Allows only opping of users in the bot's userlist. (Bitch mode on eggies.)
No Serverops - Deops any user gaining ops from a server.
CPING on Join - /CPING's users on join
Enable Idle Kick - Enables the idle kick for this channel.
+v on Join - Gives users voice on entering channel. Users on the shitlist don't get auto +v.
Disable Infoline - Disables the display of users inputlines
Disable Protection - Disables all user protection on this channel.
Auto-unban Bans - If this is checked, the bot unbans all bans after a specified time limit.
Beg For Ops - This will cause ShadowBot to beg for ops if it isn't opped in this channel.
Don't Kick On Bans - This will stop ShadowBot from kicking people out of a channel when they're banned.
Topic - If the Protect Topic button is on, the bot will try to keep the topic to the one specified.
Allow Alternate CC - You can specify an alternate command character for each channel, which can be used either with, or in place of, the default command character.
NOTE: If more than one bot in a channel has a dispute over modes or topics (i.e., one bot wants the topic +m and the other wants is -m), a Bot War may result. Deopping one of the bots and fixing its settings will fix the problem. If you have a Channel Service bot in your channel (for example, X or W on the Undernet), it's a Very Bad Idea to bring in a bot whose settings conflict, especially if the CService bot has a tendancy to be aggressive about its settings.
Access Levels
This window allows you to set the access levels required to activate the commands. -1 is the lowest and means that anyone may use the command. 0 means that anyone on the bot’s userlist may use the command. 1000 is the highest access level.
For a list of all command, open a DCC chat connection with ShadowBot and type '.HELP COMMANDS'.
Other Settings
This sets some of the other numeric settings the bot uses.
noIdleKick Access Level for which users won't be kicked for idleing
idleMinutes Number of minutes after which you can be kicked for idleing
modeOverride Access Level which allows you to override set channel modes
topicOverride Access Level which allows you to override set topic
noLagKick «OBSOLETE»
lagSeconds «OBSOLETE»
noLagNofifySecs «OBSOLETE»
infoLineTime Wait at least this long before displaying someone's infoline again.
maintSecs The length of time between runs through ShadowBot's maintenence loop.
initMem The initial number of memory records. If you are on channels with more
than 50 people, it would be a good idea to increase this number so that
it's larger than the average number of people on the channel. ShadowBot
needs one memory record for each (unique) user it has to deal with, and it
is much more efficient when it doesn't have to reallocate more memory
to keep track of more users.
strictOpAl If your access level is lower than this, you can't be opped if strict ops
is on.
strictOpOverride If your access level is at least this, you can override the previous
setting.
autoSaveMins How often ShadowBot writes the data files to disk.
ignoreTime «UNIMPLEMENTED»
dccInactive Kick people out of DCC after idling this long...
dccInactiveOverride but don't kick them if their access is at least this.
Toggles
This allows you to set some of ShadowBot’s options. These settings should be self explanitory.
Folders
This allows you to set the Plugins and DCC folders.
The Plugins Folder - Without this folder correctly set, the bot cannot use the COUNTRY command or any plugins in the Plugins folder.
The DCC Folder - Without this folder set, the bot cannot DCC files.
The Logs Folder - The folder ShadowBot saves logs to.
Strings Editor
The Strings editor allows you to edit some of the strings the bot uses. The default strings are stored in the ShadowBot application, the strings actually used are stored in the Strings file. Any changes you make go into this file. If you delete it, the strings are reset the next time ShadowBot is opened.
Flood Control
This window allows you to set up ShadowBot's flood protection.
Logging Control
Allows you to have ShadowBot automatically log text in the channels its in, or view the current logging status.
Automessages
Allows you to setup time-delayed automatic messages.
Userlist
Allows you to locally edit the user list.
Shitlist
Allows you to locally edit shitlist entries.
Partyline Configuration
The partyline feature allows more than one user to open a DCC chat connection to your bot and talk in realtime, much like on an IRC server. Text going through the partyline is displayed in the Partyline Console.
ShadowBot's partyline is compatible with the one found in eggdrop bots, a common Unix bot. Because of this compatibility, ShadowBot has the ability to connect to eggdrop bot networks.
NOTE: In this release, ShadowBot's botnet support is not completed. You cannot connect to a botnet just yet...
My Nick- This is the bot's username on the bot it's attempting to connect to.
Connect To- This is the name of the bot to connect to. Add bots to this list by making them bots in the userlist.
Bot Settings- Edits the bot's connection information.
Ping interval- How often to ping the remote bot if it's not sending text.
Access- In order to make ShadowBot respond as an Eggdrop bot would over a botnet, the "Master" and "Owner" access levels are required. These access levels define what level access you need to use some partyline commands.
Connect Automatically- Automatically connects to the botnet at launch.
Retry Delay- How often to retry a connection if it fails.
Accept Associations- The partyline allows 100,000 "channels"- 0 (the main partyline) to 99,999. It also allows these channels to have topics (associations). If you wish ShadowBot to enable the .ASSOC command locally and process ASSOC commands from other bots, you need to turn this option on. (Default is on.)
Allow Remote Boots- The .BOOT command allows you to remove someone from the botnet, if you have Master access or higher. This also allows you to boot people on other bots. To prevent users on other bots from booting people on this bot, turn this command off. (Default is on.) Users with "owner" access cannot be booted.
Password Not Required- When checked, disables the password requirment when opening DCC chat.
Currently Connected- Indicates if ShadowBot is currently connected to a botnet.
To connect to the botnet, use the LINK command. To disconnect, use the UNLINK command.
---------
Scripting and Plugins
ShadowBot has a scripting language that can be used to make auto-greets and new commands. See the files in the Plugin Docs folder for more information.
---------
Command List
For a list of commands and how to use them, open a DCC connection with ShadowBot and type ".HELP COMMANDS". You can also use the help command from the console.
---------
Hostmasks
The way ShadowBot recognizes users is by their userhost, which is sent to the bot each time someone writes a message in a channel or sends a message to the bot. This allows for identification of someone according to nick, username, and machine name. If you aren't sure of your machine name, you can get that information from a /whois on yourself. You set your nick and username from your IRC client.
Take me, for example:
Nick: DShadow
User name: DShadow
Machine name: ascend4-38.dial.umd.edu
The userhost for the above connection is DShadow!DShadow@ascend4-38.dial.umd.edu. Note the exclamation point between the nick and username and the at mark between the username and the machine name. Any time I say something in the channel, or do something that affects it (mode changes, kicks, etc), this entire string is sent by the server.
Obviously, there is a problem with this. When used as a means of identification, it is valid only when my nick and username are DShadow and I'm on the modem connected to ascend4-38 on my ISP. So we use wildcards to replace portions of the userhost. For example, I would use the following hostmask in my bot to identify myself:
*!*DShadow@*.dial.umd.edu
What this means is that anyone whose username ends in DShadow and is on any machine in the .dial.umd.edu domain is recognized by the bot. This allows for the fact that I might not always use the same nick or be connected to the same phone line. I could be more specific and use a mask like
*!*DShadow@ascend4-*.dial.umd.edu
which would only allow access if I used one specific modem pool. At school, when I have a static IP, I use the entire machine name in the mask. For example,
*!*DShadow@dshadow.dorm.umd.edu or *!*DShadow@terpmug.umd.edu
---------
How to add users to the bot
There are two ways to add users to the userlist: through the GUI usereditor, and the !ADD command.
NOTE: You should NEVER add more than one user with the same nick; there are several cases where ShadowBot does a search by nick, and will always stop at the first matching nick found. The userlist will not allow you to have more than one person with the same name.
NOTE: the usual nick parameter allows the bot to recognize you when a user performs any command in which the nick may be used.
NOTE: parameters after the access level do not need to be given. For example, if I didn’t specify anything after the access level, autoop would default to off, the protect level would be zero, and there would be no authentication password.
NOTE: Authentication passwords are CASE SENSITIVE.
Removing users from the bot
To remove a user from the bot, check the 'Deleted' button in the userlist, or use the DEL command:
!DEL usuNick
This deletes anyone with the nick specified. Please note that this does not actually remove them from the userlist, it just marks them as deleted. This allows you to undelete them before someone else is added on top of them.
The autoop parameter
The autoop parameter is a boolen variable: either on or off. Only certain characters mean on. All others mean off. When the autoop parameter is processed, only the first character in the string passed is examined. This means that "Y" and "YabbaDabbaDoo" mean the same thing. Capitilization doesn't matter
Olaf Titz- for writing Ircle 1.5.1, which ShadowBot is based on
Elixer - the startup screen
Stimmpy, Possible - unending torture in ShadowBot's infancy
PowerUser, MacJedi, Possible, GregG_, Melkor, Tandronis- ShadowBot's first testers
Peter N. Lewis - for the use of his MacTCP code
irc.amug.org - ShadowBot's residence
MacJedi - the icons
Onno Tijdgat- for getting me through the Identd code and sharing quite a bit of other code that I would never have gotten on my own, and one kick-ass IRC client
How to contact me
Email: dshadow@glue.umd.edu
IRC: Undernet: DShadow, usually on #macintosh, #macnewbies, and #mac
IRC: EfNet: DShadow, usually on #macdev
Snail Mail: John Bafford
6 Cedar Springs Ct.
Baltimore, MD 21228
The Fine Print
No warranty is provided. Use at your own risk. What else do you want from a disclaimer?
